Window Management

1. Introduction

2. Project Structure

3. Core Components

4. Architecture Overview

5. Detailed Component Analysis

6. Dependency Analysis

7. Performance Considerations

8. Troubleshooting Guide

9. Conclusion

This document explains the Electron window management system used by the application. It covers BrowserWindow creation, window dimensions and icon configuration, webPreferences security settings, development versus production loading strategies, window lifecycle events and cleanup responsibilities, error handling for failed resource loads, development tools integration, platform-specific considerations, and window state persistence.

The Electron application is organized with a clear separation between the main process (window management and backend tasks), the renderer process (React UI), and preload scripts for secure IPC bridging. Vite builds the React application for production, while a local development server serves the UI during development.

Diagram sources

• main.js

• preload.js

• utils.js

• gmail-handler.js

• smtp-handler.js

• index.html

• dist-react/index.html

• App.jsx

• main.jsx

• package.json

• vite.config.js

• electron-builder.json

Section sources

• main.js

• package.json

• vite.config.js

• electron-builder.json

• Main process window manager: Creates the primary BrowserWindow, sets dimensions, icon, and webPreferences, and handles development vs production loading.

• Preload bridge: Exposes a secure API surface to the renderer via contextBridge and IPC.

• Renderer UI: React application rendered inside the BrowserWindow.

• Auxiliary windows: OAuth window for Gmail authentication uses a separate BrowserWindow with restricted webPreferences.

• Lifecycle handlers: Ready, activate, window-all-closed, and before-quit hooks manage cleanup and platform-specific behavior.

Section sources

• main.js

• preload.js

• gmail-handler.js

The window management architecture centers on the main process creating and controlling the primary application window, delegating secure IPC to the preload script, and rendering a React UI in the renderer. Development mode loads the UI from a local Vite server; production mode loads the built React app from the dist folder. Auxiliary windows (e.g., Gmail OAuth) are created with minimal privileges.

Diagram sources

• main.js

• vite.config.js

• dist-react/index.html

• preload.js

BrowserWindow Creation and Security Configuration#

• Dimensions and icon: The primary window is configured with fixed width and height and an icon path set to a macOS icon file.

• webPreferences: Disables nodeIntegration, enables contextIsolation, disables remote module, and keeps webSecurity enabled. A preload script path is provided.

• Development vs production loading: Uses a helper to detect development mode and either loads from the Vite dev server or the built React app. In development, opens DevTools automatically.

• Error handling: Subscribes to did-fail-load to log failures when loading resources in production.

Diagram sources

• main.js

• utils.js

• vite.config.js

• dist-react/index.html

Section sources

• main.js

• utils.js

Development vs Production Loading Strategies#

• Development: The main process checks for development mode and loads the React UI from the Vite dev server on port 5173. DevTools are opened automatically.

• Production: The main process loads the built React app from the dist-react directory. It logs whether the file exists and handles load failures via did-fail-load.

Diagram sources

• main.js

• utils.js

• vite.config.js

• dist-react/index.html

Section sources

• main.js

• vite.config.js

Security Configurations#

• Context isolation: Enabled to prevent direct access to Node.js APIs from the renderer.

• Node integration: Disabled to reduce attack surface.

• Remote module: Disabled to prevent unsafe remote code execution.

• Web security: Enabled to enforce same-origin policy and mitigate XSS risks.

• Preload script: Provides a controlled IPC bridge exposed via contextBridge.

Diagram sources

• main.js

• preload.js

Section sources

• main.js

• preload.js

Window Lifecycle Events and Cleanup Responsibilities#

• Ready: On app.whenReady, the main window is created and auxiliary WhatsApp files are cleaned up.

• Activate: On macOS, if no windows remain, a new window is created.

• window-all-closed: On Windows/Linux, quits the app; on macOS, does nothing so the app stays in the dock.

• before-quit: Attempts to gracefully log out from WhatsApp and clean up cached files before the app exits.

Diagram sources

• main.js

Section sources

• main.js

Error Handling for Failed Resource Loads and Development Tools Integration#

• Production load failures: Subscribes to did-fail-load to log the URL and error description.

• Development tools: Automatically opens DevTools in development mode.

• Auxiliary window error handling: Gmail OAuth window includes a redirect listener, timeout, and closure handling.

Diagram sources

• main.js

• vite.config.js

• dist-react/index.html

Section sources

• main.js

• gmail-handler.js

Platform-Specific Considerations#

• macOS behavior: The app remains in the dock after closing windows; the activate event creates a new window when the app is activated.

• Non-macOS platforms: Quit the app when the last window closes.

• Icon configuration: The icon path targets a macOS icon file; packaging configuration defines platform targets and icons.

Diagram sources

• main.js

• electron-builder.json

Section sources

• main.js

• electron-builder.json

Window State Persistence#

• No explicit window state persistence is implemented in the main process. The window is created with fixed dimensions and icon, and no persisted bounds or state are saved or restored.

• Auxiliary windows (e.g., Gmail OAuth) are created with show=false and revealed on ready-to-show, then closed upon completion.

Section sources

• main.js

• gmail-handler.js

The main process depends on:

• Electron APIs for app lifecycle and BrowserWindow creation.

• Local utility to detect development mode.

• Handler modules for Gmail and SMTP operations.

• Vite configuration for building and serving the React app.

• electron-builder configuration for packaging and target platforms.

Diagram sources

• main.js

• utils.js

• gmail-handler.js

• smtp-handler.js

• vite.config.js

• electron-builder.json

• index.html

• dist-react/index.html

Section sources

• main.js

• package.json

• Headless browser for WhatsApp: The WhatsApp client runs with headless puppeteer and several Chromium arguments to optimize performance and reduce resource usage.

• Rate limiting: Mass messaging includes deliberate delays between sends to avoid rate limits and improve reliability.

• Build output: Vite produces optimized assets for production, reducing bundle sizes and improving load times.

Section sources

• main.js

• main.js

• vite.config.js

• Development server not running: Ensure the Vite dev server is started on port 5173 before launching the Electron app in development mode.

• Production build missing: Run the build script to generate dist-react assets before packaging or running in production mode.

• Resource load failures: Monitor the did-fail-load event logs to diagnose network or file path issues in production.

• Auxiliary window issues: For Gmail OAuth, verify redirect URI and timeouts; ensure the OAuth window is shown on ready-to-show and closed appropriately.

Section sources

• main.js

• gmail-handler.js

• gmail-handler.js

The Electron window management system establishes a secure, development-friendly, and production-ready architecture. The main process controls the primary BrowserWindow with strong security defaults, loads the React UI from a local dev server during development, and from a built distribution in production. Lifecycle hooks ensure proper cleanup and platform-specific behavior, while error handling provides visibility into resource load issues. The preload bridge safely exposes IPC capabilities to the renderer, enabling robust integration with backend handlers for Gmail and SMTP operations.